#ifndef __IM_QUARK_H__
#define __IM_QUARK_H__

#include <im_base_types.h>

/**
 * @defgroup IMQuark
 * @ingroup PublicIME
 * @{
 */

/** @type IMQuark
 *  @brief IMQuark is used to associate strings to unique ids.
 *
 *  IMQuark is an ID that identifies a string.
 */

IM_BEGIN_DECLS

typedef IMUInt32    IMQuark;

/**
 * @brief Gets the IMQuark associated with the given string.
 *
 * The im_quark_try_string() function shall return IMQuark associated with the string allocated earlier
 * by im_quark_try_string() or im_quark_from_static_string().
 *
 * If IMQuark associated with the string has not yet allocated by im_quark_from_string() or im_quark_from_static_string(),
 * im_quark_try_string() function shall return 0.
 *
 * The im_quark_try_string() function shall return 0 if string is a null pointer.
 *
 *
 * @param a pointer to an IMChar which specifies an name associated with the quark identifier.
 * @return the IMQuark associated with the string,
 *         or 0 when IMQuark associated with the string have been not allocated yet with im_quark_from_string() or im_quark_from_static_string().
 * @sa im_quark_from_string() im_quark_from_static_string()
 */
IMQuark         im_quark_try_string         (const IMChar   *string);
/**
 * @brief Gets the IMQuark identifying the given (static) string.
 *        If the string does not currently have an associated IMQuark,
 *        a new IMQuark is created, linked to the given string.
 *
 * The im_quark_from_static_string() function shall convert from the string to IMQuark representation.
 * If string is a null pointer, im_quark_from_static_string() shall return 0.
 *
 * If im_quark_from_static_string() function returns non zero value, all future calls with the same string shall return
 * the same IMQuark.
 *
 * The string argument im_quark_from_static_string() shall be in permanently allocated storage.
 *
 *
 * Note that this function is identical to im_quark_from_string()
 * except that if a new IMQuark is created the string itself is used
 * rather than a copy. This saves memory, but can only be used if the
 * string will always exist. It can be used with statically allocated
 * strings in the main program, but not with statically allocated memory
 * in dynamically loaded modules, if you expect to ever unload the
 * module again.
 *
 * @param a pointer to an IMChar which specifies an name associated with the quark identifier.
 * @return the IMQuark identifying the string.
 * @sa im_quark_try_string() im_quark_from_string()
 */
IMQuark         im_quark_from_static_string (const IMChar   *string);


/**
 * @brief Gets the IMQuark identifying the given string.
 *        If the string does not currently have an associated
 *        IMQuark, a new IMQuark is created, using a copy of
 *        the string.
 *
 * The im_quark_from_string() function shall convert from the string to IMQuark representation.
 * If string is a null pointer, im_quark_from_string() shall return 0.
 *
 * If im_quark_from_string() function returns non zero value, all future calls with the same string shall return
 * the same IMQuark.
 *
 * The string argument to im_quark_from_string() does not need to be in a parmanently allocated storage.
 *
 * @param a pointer to an IMChar which specifies an name associated with the quark identifier.
 * @return the IMQuark associated with the string.
 * @sa im_quark_from_string() im_quark_try_string()
 */
IMQuark         im_quark_from_string        (const IMChar   *string);

/**
 * @brief Gets the string associated with the given IMQuark
 *
 * The im_quark_to_string() function shall return an IMQuark representation associated with the string argument.
 *
 * If no string exists for the given IMQuark representation, im_quark_to_string() function shall
 * return NULL.
 *
 * If im_quark_to_string() function returns non-NULL value, all future calls with the same IMQuark shall return
 * the same string.
 *
 * If im_quark_to_string() function returns non-NULL, all future calls with the same IMQuark shall return the 
 * same string.
 *
 * The string pointed to by the return value shall not be modified or freed.
 *
 * @param quark an IMQuark representation.
 * @return  the string associated with the IMQuark.
 */
const IMChar*   im_quark_to_string          (IMQuark         quark);
/**
 * @brief Returns a canonical representation for a string.
 *        Interned strings can be compared for equality by
 *        comparing the pointers, instead of using strcmp().
 *
 * TODO
 * The im_intern_string() function
 * The string pointed to by the return value shall not be modified or freed.
 * @param string a string
 * @return a canonical representation for the string.
 */
const IMChar*   im_intern_string            (const IMChar   *string);
/**
 * @brief Returns a canonical representation for a string.
 *        Interned strings can be compared for equality by
 *        comparing the pointers, instead of using strcmp().
 *
 * TODO
 * The im_intern_static_string() function
 * im_intern_static_string() does not copy the string, therefore
 * string must not be freed or modified.
 *
 * The string pointed to by the return value shall not be modified or freed.
 *
 * @param string a string
 * @return a canonical representation for the string.
 */
const IMChar*   im_intern_static_string     (const IMChar   *string);


IM_END_DECLS
/** @} */

#endif
/*
vi:ts=4:nowrap:ai:expandtab
*/
